Collection of Tools & Utilities/Collection of Tools and Utilities.iso/asmutil/tbones07.zip/TSRKEY.ASM

Assembly Source File | 1991-01-20 | 15.2 KB | 369 lines

;***************************
PAGE    55,132          ;Format .LST listing at 55 lines by 132 columns.
TITLE   TSRKEY Version 0.4 Jan 20 1991 Robert Curtis Davis
SUBTTL  Introduction
;******************************************************************************
;
;       TSRKEY.ASM      Version 0.4     Jan 20 91
;       A part of the TBONES software package.
;
;       Copyright (C) 1990, 1991 by Robert Curtis Davis,
;    All Rights Reserved.
;
;    DESCRIPTION:
;    ASM Program template for Terminate-and-Stay-Resident (TSR) programs
;        that are activated by a specified HotKey..
;
;    PURPOSE:
;       Provides a skeletal framework program useful as a starting point
;       in the design of your own HotKey TSRs.
;
;                   E-mail address:
;              Internet: [e-mail]
;
;                          US Mail:
;                                   430 Bahama Drive
;                                   Indialantic, FL 32903
;
;***************************************************************************
;
; Special thanks to David Kirschbaum, whose Toad Hall Tweaks significantly
; improved TBONES' code:
;
;v0.11    Toad Hall Tweak, 25 Nov 90
; - Idiosyncracy: I like my constant labels all-upper-case
;   and my variable labels lower-case.
; - Load AX with words, not byte-by-byte
; - Load ES directly with environ seg, no need to pass thru AX.
; - Save ES directly to variable, no need to pass thru AX.
; - Let compiler do basic arithmetic (figuring paras of memory to save).
; - Use processes just to be neat.  (That FAR NewInt09 is important!)
; - INS is a reserved word for TASM v1.0. Changed to INSRT.
;**************************************************************************
SUBTTL  Code Segment (Resident)
PAGE
;**************************************************************************
;
CodeSeg        segment
                assume  cs:CodeSeg,ds:CodeSeg
BeginDump       EQU     $       ;This, from Roy Silvernail, makes
                                ;TASM v.1.0 happy below.
;
        org    2CH        ;0.11
envseg        label    word        ;0.11
;
        org    100h        ;ORG for all COM programs.
;
Entry           PROC    NEAR            ;v0.11
        jmp    TSRinit        ;Jump over resident portion and
                    ;initialize things and make code
                    ;between Entry: and TSRinit: resident.
;
; Old Keyboard Interrupt Vector (Int 09h handler address) is stored
; here during TSR initialization:
oldint09        dd      ?
;
Entry           ENDP                    ;v0.11

; For this HotKey TSR Template, specify Keyboard Interrupt 09h as the Hook:
HOOK09            equ     09h   ;Hooked Interrupt number.
;
bellgate    db    0    ;Gate closed (=1) when in Bell routine.
                ;Gate open (=0) when not in Bell routine.
;
; EQUs defining Key Flag weights in the Key Flag Byte:
RSHIFT        equ    00000001B        ;Right Shift Key Flag weight.
LSHIFT        equ    00000010B        ;Left Shift  Key Flag weight.
CTRL        equ    00000100B        ;Ctrl        Key Flag weight.
ALT        equ    00001000B        ;Alt         Key Flag weight.
;SCROLL          equ     00010000B               ;Scroll Lock Key Flag weight.
;NUM             equ     00100000B               ;Num Lock    Key Flag weight.
;CAPS            equ     01000000B               ;Caps Lock   Key Flag weight.
INSRT        equ    10000000B        ;Ins         Key Flag weight.
;*************************************************************************
;       Mask to mask out Num, Caps, and Scroll Lock bits from key flag byte.
LockKeyMask     EQU     10001111B
;
;       Your HotKey is specified here:
;       (This sample HotKey is set for Ctrl-Alt-K)
;
; Specify TSR's HotKey Shift Keys:
KEYFLAGBYTE    equ    CTRL+ALT        ;HotKey Flags
;
; Specify TSR's HotKey Scan Code:
HOTKEY          equ     25h                     ;'K' key.
;
;*************************************************************************
SUBTTL User-supplied TSR Routine
PAGE
;*************************************************************************
ROUTINE         PROC    NEAR
;*************************************************************************
;    Code for your HotKey-triggered TSR routine  GOES HERE:
;    ( Here, a dummy routine has been placed which simply rings the
;      terminal Bell whenever the TSR is triggered. )
;
;    Announce this dummy TSR's trigger by a Bell signal:
;
Enter:
                mov     al,07h          ;al = ASCII Bell.
                mov     bh,0            ;Video page.
                mov     cx,1            ;No. of bytes to write.
                mov     ah,0Eh          ;BIOS Int10,OEh=TTY Screen.
                Int     10h             ;Write ASCII Bell to screen.
;
Exit:
                ret                     ;Return from TSR routine.
;
ROUTINE         endp
;
;    End of your HotKeyed TSR routine.
;***************************************************************************
SUBTTL Hooked Interrupts
PAGE
;***************************************************************************
;
NewInt09    PROC    FAR        ;v0.01
;
; The following three instructions often are said to "simulate an interrupt"
; that calls the PRIOR interrupt handler routine and then the prior interrupt
; handler's IRET instruction pops the flags and returns here to the point
; after the following CALL instruction.
;    The reason for "simulating the interrupt" here is to give prior (and
; presumably more time-critical) handlers a shot at processing this interrupt
; before we process with this TSR's code.
;
        pushf            ;Push flags as a true interrupt would.
                cli                     ;Be sure interrupts are disabled.
        call    CS:oldint09    ;Call FAR PTR address of old interrupt
;                    ;     handler routine.
;
;
                push    ax      ;Prepare to check for Hotkey.
                push    bx      ;Save all registers (DS is already pushed).
                push    cx
                push    dx
                push    si
                push    di
                push    bp
                push    ds
                push    es
;
                push    CS              ;Set up data segment
                pop     DS              ;register to point to code segment.
;
                ASSUME  DS:CodeSeg      ;v0.01
;
;       Determine if the current Keyboard Interrupt (Int09h) occurred
;       because this TSR's HotKey was pressed:
                in      al,60h          ;Get current Key Scan Code.
                cmp     al,HOTKEY       ;Is it HotKey's Scan Code?
                jne     Exit09          ;Exit if not.
                mov     ah,02h          ;Int16h,Fcn02h:GetKEYFLAGBYTE.
                Int     16h             ;Return Key Flag Byte in al.
                and     al,LockKeyMask  ;Mask out Num, Caps, Scroll Lock bits.
                cmp     al,KEYFLAGBYTE  ;Are the HotKey Flags active ?
                jne     Exit09          ;Exit if not.
;
;       At this point, Hotkey is known to have been pressed. First, purge
;       the DOS Keyboard type-ahead buffer of the hot key(s) so they won't
;       be passed on to DOS:
;
ClrKbdBuf:      ;Clear Keyboard buffer:
                mov     ah,01h          ;Get Keyboard buffer status
                int     16h             ;via BIOS Interrupt 16h.
                jz      BufClr          ;Jump if buffer empty.
                mov     ah,00h          ;Get key from buffer (to purge it)
                int     16h             ;via BIOS Interrupt 16h.
                jmp     ClrKbdBuf       ;Loop back to purge another key.
BufClr:
;
; We shall allow other interrupts to occur during our TSR ROUTINE.
; If we didn't allow other interrupts (through the STI instruction),
; we could lock out time-critical interrupts from access to the CPU during
; our TSR routine. However, by allowing interrupts during our routine, we
; have an increased responsibility to make sure critical portions of our
; own code is not re-entered. (The "bellgate" stuff below is an example
; of a measure necessary to keep us from re-entering our own TSR's code).
; What we really want to do by allowing interrupts is to make the CPU avail-
; able to OTHER critical interrupt service routines WITHOUT swarming all over
; ourselves through multiple detections of our own HotKey.
;               This "gate" technique is a good one to keep in
;               mind whenever you have a code region in an interrupt handler
;               that needs to be protected from re-entry:
;
                cmp     bellgate,0      ;Is it clear to re-enter Hotkey code?
                jne     Exit09          ;Exit if not,
                mov     bellgate,1      ;Else, close gate and proceed.
;
                STI                     ;Allow other interrupts in our TSR.
;
                call    ROUTINE         ;All is clear!, so call routine.
;
                mov     CS:bellgate,0   ;Open gate allowing new HotKey detect.
;
Exit09:
                pop     es              ;Restore all registers
                pop     ds
                ASSUME  DS:NOTHING      ;v0.01
                pop     bp
        pop    di
        pop    si
        pop    dx
        pop    cx
        pop    bx
        pop    ax
;
;
;    Return from this TSR's Keyboard Interrupt 09h handler routine:
        iret
;
NewInt09    ENDP            ;v0.01
;
;*************************************************************************
;
;    -END OF TSR's RESIDENT CODE-
;    Only the code above will remain locked in memory
;        after the initialization performed below.
;*************************************************************************
SUBTTL  TSR Initialization Code (Nonresident). The "BOOSTER".
PAGE
;*************************************************************************
;       BEGINNING OF TSR's INITIALIZATION CODE:
;    The following code is protected in RAM *ONLY* during initialization
;        of the TSR that occurs when the TSR name is first entered
;        at the DOS command level. All the following code is abandonned
;        unprotected in RAM after the Terminate-and-Stay-Resident
;        call to Function 31h of DOS Interrupt 21h below. This
;        is allowed to happen because the code's work is complete at
;        that point. The code will be overwritten as the memory which
;        it temporarily occupied is needed by DOS for other purposes.
;         I have seen this following section of code colorfully called
;        the TSR "Booster". And this is quite appropriate since the code
;        sits here, strapped to the very end of the code. It is of use
;        only during the initialization of the TSR, when it is used to
;        put the TSR into "orbit" (residency), and after which it is
;        "jettisoned" by the DOS TSR call, Int 21h, Fcn 31h.
;
TSRinit         PROC    NEAR                            ;v0.11
EndDump         EQU     $       ;From Roy Silvernail. Keeps TASM v.1.0 happy.
;
; TSRKEY requires DOS Version 2 or later. Be sure DOS Version 1 not used:
;
;       Get DOS Version Number:
                mov     ah,30h                  ;Fcn 30h = Get DOS Version
                int     21h                     ;DOS Version = al.ah
;
;       If this is DOS v.1.x, this TSR cannot work, so go print message
;       and exit without installing:
                cmp     al,1         ;Is this DOS Version 1.x?
                ja      DOSverOK     ;If not, DOS version is OK.
;
DOSver1:
;If here, DOS Version 1.x is being run and TSR won't work, so bail out:
;
        mov    dx,OFFSET BailOutMsg    ;TBONES needs DOS 2.x or later.
        mov    ah,09h            ;Say we're sorry, but NO GO
        int    21h            ;via DOS.
                pop     bx                      ;Clear stack.
        int    20h            ;Terminate without installing
                        ;in only way DOS 1.x knows.
;
BailOutMsg:
                db      0Dh,0Ah
                db      'Sorry. TSRBONES needs DOS v.2+. You have v.1.x'
                db      0Dh,0Ah,'$'
;
DOSverOK:
;       If here, DOS version is 2.0 or later. TSR can work, so proceed.
;
;       To conserve RAM usage, release from memory the copy of the DOS
;    Environment passed to this TSR (this assumes, of course, that
;    your Interrupt handler routine will not need to reference this
;    de-allocated Environment):
;
        mov    ES,envseg        ;ES=PSP's environment seg v0.11
        mov    ah,49h            ;DOS Fcn 49h = Release Memory
        int    21h            ;Release it via DOS interrupt.
;
; In order to make the TSR's command name show under the "owner" column in
;    the "MAPMEM" command of Kim Kokkonen's excellent TSR Mark/Release
;       package, allocate a tiny 1-paragraph "Pseudo-Environment" here which
;       contains nothing but the TSR name. This costs only 16 bytes in
;       TSR resident code.
;
; Allocate the memory needed by the tiny 'Pseudo-Environment":
        mov    bx,1            ;Allocate one parag. (16bytes)
        mov    ah,48h            ;and return allocation
        int    21h            ;segment in ax via DOS call.
;
                mov     ES,ax                   ;Pseudo-Env. Segment to ES.
        mov    si,OFFSET PseudoEnv    ;si=source string OFFSET.
        mov    di,0            ;di=destination string OFFSET.
        mov    cx,ENVLNGTH        ;cx=Bytes in Pseudo-Env.string.
        cld                ;Forward string move direction.
        rep    movsb    ;Move Pseudo-Env. string @ DS:si to ES:di
;
; Set PSP's Environment segment pointer to point to tiny Pseudo-Environment.
        mov    envseg,ES
;
;*****************************************************************************
; Hook Interrupt 09h vector:
;
;       Get Old Interrupt Vector:
                mov     ax,3500H+HOOK09         ;Get Hooked interrupt vec v0.11
        int    21h            ;Int.Vector in ES:BX via DOS.
;
;    Save Old Interrupt Vector:
                mov     Word Ptr oldint09,bx      ;Save Offset of Old Interrupt.
                mov     word ptr oldint09+2,ES    ;save segment           v0.11
;
;       Install New Interrupt Vector to this TSR's "NewInt09:" Label:
                mov     ax,2500H+HOOK09         ;Set Hooked int vector v0.11
                mov     dx,offset NewInt09      ;dx=Offset of New Int Handler.
        int    21h            ;Set New Int via DOS.
;
; Announce the TSR's Installation:
        mov    dx,Offset InstallMsg    ;DX points to message.
        mov    ah,09h            ;DOS Fcn. 09h=Display String.
        int    21h            ;Display String via DOS.
;
; Lock resident code in memory via Terminate-and-Stay-Resident (TSR) DOS call:
;
;v0.11    DX requires size of resident code (in 16-byte paragraphs)
;    This awkward construct is required to keep
;    DOS Function 31h happy.  Notice how we first compute
;    the length of the TSR code in bytes [i.e., end of
;    the TSR code (TSRinit) minus start of the TSR code
;    (0, our CodeSeg)], round it up to the next whole paragraph ( + 0Fh),
;    and then divide by 16 (SHR 4) to get the number of resident paragraphs:
;
;       Roy Silvernail discovered that the EndDump and BeginDump constants
;       kept his TASM 1.0 assembler happy on the following statement:
                mov     dx,(EndDump-BeginDump+0FH)/16   ;v0.11
;
        mov    ah,31h            ;DOS FCN 31h=TSR Call.
        int    21h            ;Go Resident via DOS TSR call.
;
PseudoEnv:      DB      ' ',0,0,1,0,'TSRKEY',0
ENVLNGTH    EQU    $-PseudoEnv
;
InstallMsg:
        db    0Dh,0Ah
        db    'YOUR HOT KEY TSR IS NOW INSTALLED.'
        db    0Dh,0Ah
                db      'HotKey => Ctrl-Alt-K'
        db    0Dh,0Ah
        db    0Dh,0Ah
                db      'TSRKEY Version 0.4'
        db    0Dh,0Ah
                db      'Copyright (C) 1990, 1991 by Robert Curtis Davis'
        db    0Dh,0Ah,'$'
;
TSRinit    ENDP                    ;v0.11

CodeSeg        ends
        end    Entry
;
;******************************************************************************